Apple Developer Connection 1998 Fall: Game Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ Apple Developer Connection 1998 Fall: Game Toolkit / Disc.iso / SDKs / Apple Game Sprockets / InputSprocket / InputSprocket Developer Notes next >

Wrap

Text File | 1998-07-16 | 20.8 KB | 459 lines | [TEXT/MPS ]

InputSprocket 1.3 Release Notes ------------------- General Release Notes: Although not a change, a clarification is needed on how exclusive items operate particularly with regards to hat-type switches (direction-pads, digital joysticks and hat switches). A group of mutually exclusive items is a group of items where activation of one item automatically deactivates other items in the group. A group of mutually exclusive items might be assigned to a hat. An example is "look" functionality which allows the user to different directions from the cockpit in a flight simulator implemented as four different button needs. A problem will arise if the group of items only uses the activation of these buttons to select which item is active. This problem will only arise if the program in question does not properly handle combinations of the button activations. For example, if I assign "look right" to the right item of a hat and "look forward" to the top item of a hat. Now, if I press right on the hat I will look right. If I now wiggle my thumb upwards so that up is activated (up and right are now simultaneously activated) I will look forward. If I slide my thumb back to the right, I will release the "look up" item, but since the "look right" item was activated the whole time, I do not reactivate the "look right" function. I now have my thumb holding the hat right, but I am looking forward. In fact, since the "look right" item is already held down, it is the ONLY button on the entire controller which cannot be pressed and it becomes impossible to look right without releasing the hat and pressing it right again. Symptoms of this are that it is easier to look right by pressing forward and sliding right to the corner of the d-pad than it is to press right directly! The only way to correct for this is to consider both presses (kISpButtonDown) and releases (kISpButtonUp) of any button needs which are exclusive. In this case, when right is pressed, the right function would be activated. When the up function is activated, both items are now activated. The InputSprocket client can either deactivate the original right function and switch to the up function, or it can remain with the right function and only switch to the up function when the right button is released. If the hat is moved to the right again and the up function is released, then the client should switch back to the right function if it has switched away. Proper handling of releases for button needs will allow mutually exclusive functions to operate properly. Before you ship any application, check to make sure you get no warnings when running with InputSprocketDebugLib and the debug versions of the drivers. Changes from 1.2 ----------------- A resource definition file "InputSprocket.r" has been added. You can use this file to create a Rez '.r' file to build the ISp resources into your application. One of the templates is for the 'tset' resource created by the ISp keyboard driver. Note this templete is ONLY valid for a 'tset' generated by the keyboard. The only way to tell who created the 'tset' is to examine the 'setl' resource that points to it. The new sample code for DroneZone uses this template so that the defaults for the keyboard are in a Rez file and are easily updated when then application's list of needs changes. You still have recreate the sets for mice and gaming devices when your needs list changes during development, but not having to re-setup all the keyboard keys every time should be a big win. (Note: You may have to delete your InputSprocket Preferences file in order to get the new defaults from the application -- or change the subCreatorCode passed to ISpInit.) New drivers have been added: InputSprocket CH Trackball: support for CH Trackballs InputSprocket Contour: support for the Contour Mouse InputSprocket MicroSpeed: support for MacTRAC and MouseDeluxe InputSprocket NoHands: support for the NoHands mouse InputSprocket ArenaMouse: support for the 'Arena' 3D mouse InputSprocket MacALLY: support for the MacALLY Joystick InputSprocket USB: support for some USB devices on a Mac with USB Special thanks to Jeremy Erwin who is not affiliated with MacALLY, for the code to support the MacALLY stick. In the debug folder, there is a new driver: InputSprocket NeedView: useful for debugging your application All mice and keyboard drivers are 'passthru' in the debug versions. This means that it is VERY important you make sure you also test with the release versions of the drivers, since some things will work fine with the debug versions but not with the release drivers. On the other hand, you will never get stuck in the debugger without being able to type and/or move the cursor. InputSprocket resets all elements to 'zero' values (symmetric axis are reset to the center) across suspend/resume. It is the responsibility of individual ISp drivers to push data to any elements which are non-default valued when the driver is reactivated. ISp drivers must insure that they are Virtual Memory (VM) safe. InterruptTickle is only called at 'VM safe' times. However, ISp drivers must be aware of any callbacks they install directly, and whether they can occur during 'VM unsafe' times. If so then the ISp Driver is responsible for insuring that it is memory resident. Drivers which use ADB can include InputSprocketDefer.h and link to InputSprocketDeferLib which provides services so that ADB handlers are deferred until paging safe time. This way, the driver does not have to be held (although it will be resident under most conditions if it is actually being called many times a second). Drivers which use USB via USBHIDUniversalModule will automatically be deferred until 'VM safe' times, so do not have to worry about this problem. Many minor bugs have been fixed. 68K support has been added. 68K InputSprocket is only available through CFM-68K. Some new constants were added to InputSprocket.h. InputSprocket 1.2 Release Notes ----------------- General Release Notes: This release involves many minor improvements to the InputSprocket drivers, including an improved user interface (UI) for axis. Some new drivers have also been added. Several problems and bugs have been addressed. A new resource has been defined (kISpApplicationResourceType = 'isap') which all applications which use InputSprocket should put (ID 0) in their resource fork. They should always set bit 0 (kISpAppResFlag_UsesInputSprocket) and set bit 1 (kISpAppResFlag_UsesISpInit) if they use the high level API (ie they call ISpInit, ISpConfig, etc... in other words they have a needs list). The rest of the bits and reserved fields should be set to 0. A new ISpElementKind has been added: kISpElementKind_Delta which specifies a Fixed point number of inches moved. InputSprocket Mouse and InputSprocket Kensington now register elements of this kind in the low level. The high level (through ISpConfigure) supports axis as well as delta kinds. This kind is very useful if you want to control a cursor. A new definition of ISpNeed can be used by defining USE_OLD_ISPNEED_STRUCT to 0. The first reserved field (a short) was changed to two UInt8s: playerNum and group. Use playerNum to tell the driver some needs are related to a particular player (on the same machine). The SprocketInvaders source code will be reved to use this field. Group is used to group items together, such as a look up, look down need (assuming you can't use an axis). You should also group items together that have the same effect, but are 'tuned' button, axis, and delta versions. The current ISp drivers do not use this hinting, yet. Some new definitions for the ISpNeedFlagBits have been added. If you use the new definition, make sure you check your code for cases where you were initializing the struct. You now may be misaligned, and many compilers will NOT generate a warning. High Level Release Notes: InputSprocket needs a 640x480 display (or larger) in order for its dialog to work. If you are asking DrawSprocket for a smaller display size than that you should switch out before calling InputSprocket. Information about how to get saved sets ('setl' Resources) to work is below under the InputSprocket 1.0 Release Notes AbsoluteTime and UnsignedWide are in the latest types.h (ETO #20 or later). /*typedef UnsignedWide AbsoluteTime; struct UnsignedWide {UInt32 hi;UInt32 lo;};*/ InputSprocket Mouse supplies pseudo-buttons in the high level for modifier keys in combination with mouse clicks. You will have at least four buttons (where some may actually be command/shift/control/option-click on one-button mice) for any mouse device. This should make it straightforward to port games which expect a two button mouse: use ISp with delta and button needs -- and dont worry about what type of device the user has. Changes from 1.1 ----------------- - InputSprocket Speech added back to distribution (crashing bug fixed) - InputSprocket Gravis supports Blackhawk and uses new UI (new save set format) - InputSprocket Thrustmaster uses new UI (new save set format) - InputSprocket Joy completely revised, renamed InputSprocket CH, now supports multiple devices seperately and supports up to 8 buttons and 4 hats per device (new save set format) - InputSprocket Kensington added, supports kensington devices regardless of their software - InputSprocket Sidewinder 3D Pro added, supports Microsoft Sidewinder joystick - InputSprocket AppleJack added, supports Pippin/AppleJack controller - InputSprocket Keyboard supports modifier keys in conjunction with a normal key (now either Escape or Cmd-Q are valid for kISpElementLabel_Btn_PauseResume) - Device and element strings have been reviewed, and some have been changed - ISpConfigure saves and restores the port. - A new function: ISpTimeToMicroseconds has been added. - There are some new bits defined for ISpNeedFlagBits. - Some new element labels have been added. - Old saved sets for devices other than mouse and keyboard do not work Incomplete list of devices input sprocket supports -------------------------------------------------- - Thrustmaster FCS, Thrustmaster WCS, Thrustmaster RCS - Gravis Gamepad, Gravis Firebird, Gravis Mousestick II, Gravis Blackhawk - CH Jetstick, CH Flightstick Pro, CH Pro Pedals, CH Pedals, CH F16 Fighterstick, CH Gamepad, CH Pro Throttle - Kensington TurboMouse 4.0, TurboMouse 5.0, Thinking Mouse, Kensington Mouse, CoStar Stringray trackball - Microsoft SideWinder 3D Pro - AppleJack/ Pippin Controller - Speech Recognition - Keyboard - traditional Apple 'id handler 1' mouse and 100% compatable mice - modern 'id handler 4' mice including Logitech Trackman Marble (see the technote "Space Aliens Ate My Mouse") Known Problems in 1.2 --------------------- - Kensington Mouse-in-a-box reports two buttons (only the first one works) - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o ALPS software) - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button Power') is installed (appears as 1 button mouse w/o Mouse Systems software) - CH Trackball PRO does not appear - Thrustmaster software generates keyDowns if so configured with ThrustWare (fix is to configure all buttons to do nothing in ThrustWare) - Machines based on the Tanzania motherboard (Motorola StarMax, APS MPower, Apple PowerMacintosh 4400) will always show an extra Mouse device for the PS/2 mouse regardless whether one is plugged in (even though the 4400 has no PS/2 ports, the phantom ADB devices for them are still created). The PS/2 mouse only reports one button. - When a Sidewinder 3D Pro stick is connected, an extra mouse device is shown which is active when the 'mouse/joystick' switch is switched to 'mouse'. - It is unstable to have multiple applications use InputSprocket simultaneously. If your application can be suspended and uses InputSprocket you should use ISpShutdown and ISpStartup so that InputSprocket is off while you are in the background. This is a bug (since 1.0) and will be fixed in the next version. If you are a user you can work around this problem by not running more than one InputSprocket application at the same time. - When debugging, you may need to deactivate the Mouse and Keyboard drivers in order to be able to interact with your debugger. InputSprocket 1.1 Release Notes ----------------- General Release Notes: We recommend that if you are using input sprocket version greater than 1.02 that you no longer support any third party joystick APIs. You must not support those APIs at the same time as you have InputSprocket devices enabled. High Level Release Notes: If you are using InputSprocket via the high level (ISpConfigure and ISpInit and so on). We recommend that you only use the axis and button data types and build the controls that you need out of those types. This will get you the best support. Many of the drivers are going to only primarily emulate those datatypes. Known Problems in 1.1 --------------------- - Kensington Trackball does not appear if Kensington software is installed (appears w/o Kensington software) - ALPS GlidePoint does not appear if ALPS software is installed (appears w/o ALPS software) - Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button Power') is installed (appears as 1 button mouse w/o Mouse Systems software) - CoStar Stingray Trackball does not appear if CoStar software ('Stingray') is installed (appears w/o CoStar software) - CH Trackball PRO does not appear - Thrustmaster software generates keyDowns if so configured with ThrustWare (fix is to configure all buttons to do nothing in ThrustWare) Changes from 1.02 ----------------- - new APIs (ISpStartup, ISpShutdown, ISpTickle, ISpDevices_ActivateClass, ISpDevices_DeactivateClass) - some general ui improvements in both appearance and performance have been made - new driver InputSprocket Joy (supports some features of JoyManager devices -- ie mainly CH products) - new driver InputSprocket Thrustmaster (supports FCS, WCS, RCS) - new driver InputSprocket Gravis (supports MouseStick, Firebird, GamePad) - new driver InputSprocket Speech (you must activate explicitly and requires ISpTickle be called) - InputSprocket Mouse changed to have new UI and is implemented via ADBMgr directly instead of a CursorDeviceMgr Patch - InputSprocket Keyboard has been slightly changed if there is only one page - driver function to plot icons has been changed (faster) - bug when you select a 0 length name to save a set has been fixed - bug involving choosing monitor has been fixed (might chose something other than the main monitor randomly) - CH Flightstick, CH Gamepad, CH Jetstick and MacEnjoy no longer generate a mouse device - a crashing bug involving multiple applications using input sprocket simultaniously has been fixed - a very small memory leak involving ISpConfigure has been fixed - DONT_USE_OLD_INPUT_SPROCKET_LABELS changed to USE_OLD_INPUT_SPROCKET_LABELS in InputSprocket.h - a bug where InputSprocket Keyboard and InputSprocket Mouse called InitGraf has been fixed InputSprocket Speech Notes -------------------------- - you must call ISpTickle in order for InputSprocket Speech to work - you must call ISpDevices_ActivateClass(kISpDeviceClass_SpeechRecognition) to turn InputSprocket Speech on - requires SpeechRecognition extension 1.5.1 (PlainTalk 1.5) InputSprocket Joy Notes ----------------------- - supports all JoyManager devices as a single input sprocket device. - UI may show popups for controls the device does not have - JoySimpleData based - only supports the trigger and three additional buttons - digital pointing devices (ex. CH Gamepad's pad) are treated as a pair of axis not a POV Hat InputSprocket 1.02 Release Notes ----------------- There is a new InputSprocket.h that has new versions of the names for the labels as well as additional labels. The following bugs were fixed in the 1.01 or the 1.02 releases. - keyboard ui now generates better names than Min/Max for axis if ElementLabel is useful - various problems with alignment and growing of dialog were fixed - flickering with icons in thrustmaster and mouse fixed - stub library included in this release with file type 'stub' - axis flipping check box now works again for the mouse driver - ISpDevices_Extract functions no work when an exact count is passed to them - Icon plotting is more robust. - The OK button is no longer hilited when the keyboard is active. - InputSprocket will now unload the drivers when the last fragment is unloaded - InputSprocket no longer leaks memory when you quit in the suspended state - when there are no devices to configure and ISpConfigure is called it will display a warning instead of doing nothing - ISpSuspend no longer leaks 10,000 bytes every call The following bugs are known: -There is an incompatability with the mouse driver and the Kensignton trackball software that causes no mice devices to appear. -There is a incompatability with the Kensington trackball that causes an extra mouse device to appear when the hardware is installed and the software is not installed. InputSprocket 1.0 Release Notes ----------------- Please report all bugs to sprockets@adr.apple.com! Release Components ------------------ InputSprocket Release Notes - this file InputSprocket.h - the header file to compile with InputSprocketLib - release version of the library InputSprocketDebugLib - debugging version of the library InputSprocketStubLib - version of the library to link to InputSprocket Keyboard - keyboard plug-in InputSprocket Mouse - mouse plug-in InputSprocketTest - test program InputSprocketTest.µ - Metrowerks 8 project to build test InputSprocketTest Sources - sources for test program Place InputSprocket Keyboard, InputSprocket Mouse and InputSprocketLib or InputSprocketDebugLib in the Extensions folder. Place InputSprocket.h in your development environment's C Headers folder. Place InputSprocketStubLib in your development environment's Libraries folder. WARNING: don't place both the debugging and non-debugging versions of the library in the search path or you will not be sure which version you will be using. Dependencies ------------ InputSprocket requires the latest Universal Headers -- version 2.1.2 or later. You can find them on E.T.O. #20, the MacOS SDK CD-ROMs, Apple's web-site, or a number of other locations. If you have a problem with the "AbsoluteTime" type usage, then you aren't using the latest Types.h file. Compatability with Prereleases ------------------------------ InputSprocket 1.0 is not compatible with any of the pre-release versions of InputSprocket. You should throw out all DR versions. Changes to 'setl' Resource -------------------------- The format for the set list resource ('setl') was changed at the last minute. A resedit TMPL resource is automatically installed in the preference file and the format is as follows: -- header -- Version (4 bytes) The current version is now 2. Count (4 bytes) -- each entry -- name (64 bytes) A pascal string set length (4 bytes) The length of the set device class (4 bytes) The device class of the device device identifier (4 bytes) The device identifier of the device flags (4 bytes) Same flags as in the header reserved1 (4 bytes) Reserved by apple set to zero. reserved2 (4 bytes) Reserved by apple set to zero. reserved3 (4 bytes) Reserved by apple set to zero. set resource id (2 bytes) The resource id of the set. reserved4 (2 bytes) Reserved by apple set to zero. Special Considerations ---------------------- - Your game should use the Escape key to pause and resume play. The element that corresponds to the Escape key is labelled ISpElementLabel_Start. If your game uses virtual elements then the first button need that is labelled ISpElementLabel_Start is auto- configured to the Escape key, and the user can't change this in the ISpConfigure dialog. - Your game may provide default and optional configurations for the keyboard, the mouse and any other devices. This is done by including 'setl' and 'tset' resources a resource file, such as the application's, that is open when ISpInit and ISpConfigure are called. Since the format of the 'tset' resource is determined by the device, it is easiest to use the configuration dialog to establish the desired configurations then copy them from the Preferences file into your resource file. 1. Remove the InputSprocket Preferences file from the Preferences folder. 2. Run your game, and invoke the ISpConfigure dialog. 3. Configure and save as many sets as you like for any and all devices. 4. Quit. 5. Use ResEdit to move the 'setl' and 'tset' resources to your resource file. 6. Edit the 'setl' resource using the 'TMPL' supplied in InputSprocketSimpleTest.rsrc. 7. Change the flags field to $00000002 for the default entry for a given device or $00000004 for any other entry for that device. 8. Again remove the InputSprocket Preferences file from the Preferences folder so you can test with a clean slate. 9. Rebuild your game and try out your new configurations.